<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<title>Source code</title>
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
</head>
<body>
<div class="sourceContainer">
<pre><span class="sourceLineNo">001</span><a name="line.1"></a>
<span class="sourceLineNo">002</span>/*<a name="line.2"></a>
<span class="sourceLineNo">003</span> * Copyright (C) 2014 Archie L. Cobbs. All rights reserved.<a name="line.3"></a>
<span class="sourceLineNo">004</span> *<a name="line.4"></a>
<span class="sourceLineNo">005</span> * $Id: OnChange.html 842 2015-03-07 18:20:42Z archie.cobbs $<a name="line.5"></a>
<span class="sourceLineNo">006</span> */<a name="line.6"></a>
<span class="sourceLineNo">007</span><a name="line.7"></a>
<span class="sourceLineNo">008</span>package org.jsimpledb.annotation;<a name="line.8"></a>
<span class="sourceLineNo">009</span><a name="line.9"></a>
<span class="sourceLineNo">010</span>import java.lang.annotation.Documented;<a name="line.10"></a>
<span class="sourceLineNo">011</span>import java.lang.annotation.ElementType;<a name="line.11"></a>
<span class="sourceLineNo">012</span>import java.lang.annotation.Retention;<a name="line.12"></a>
<span class="sourceLineNo">013</span>import java.lang.annotation.RetentionPolicy;<a name="line.13"></a>
<span class="sourceLineNo">014</span>import java.lang.annotation.Target;<a name="line.14"></a>
<span class="sourceLineNo">015</span><a name="line.15"></a>
<span class="sourceLineNo">016</span>/**<a name="line.16"></a>
<span class="sourceLineNo">017</span> * Annotation for methods that are to be invoked whenever a target field in some target object changes during a transaction,<a name="line.17"></a>
<span class="sourceLineNo">018</span> * where the target object containing the changed field is found at the end of a path of references<a name="line.18"></a>
<span class="sourceLineNo">019</span> * starting from the object to be notified.<a name="line.19"></a>
<span class="sourceLineNo">020</span> * See {@link org.jsimpledb.ReferencePath} for more information about reference paths.<a name="line.20"></a>
<span class="sourceLineNo">021</span> *<a name="line.21"></a>
<span class="sourceLineNo">022</span> * &lt;p&gt;&lt;b&gt;Method Parameter Types&lt;/b&gt;&lt;/p&gt;<a name="line.22"></a>
<span class="sourceLineNo">023</span> *<a name="line.23"></a>
<span class="sourceLineNo">024</span> * &lt;p&gt;<a name="line.24"></a>
<span class="sourceLineNo">025</span> * In all cases the annotated method must return void and take a single parameter, which is compatible with one or more<a name="line.25"></a>
<span class="sourceLineNo">026</span> * of the {@link org.jsimpledb.change.FieldChange} sub-types appropriate for the field being watched.<a name="line.26"></a>
<span class="sourceLineNo">027</span> * The method may have any level of access, including {@code private}.<a name="line.27"></a>
<span class="sourceLineNo">028</span> * The method parameter type can be used to restrict which notifications are delivered. For example, an annotated method<a name="line.28"></a>
<span class="sourceLineNo">029</span> * taking a {@link org.jsimpledb.change.SetFieldChange} will receive notifications about all changes to a set field,<a name="line.29"></a>
<span class="sourceLineNo">030</span> * while a method taking a {@link org.jsimpledb.change.SetFieldAdd} will receive notification only when an element<a name="line.30"></a>
<span class="sourceLineNo">031</span> * is added to the set.<a name="line.31"></a>
<span class="sourceLineNo">032</span> * &lt;/p&gt;<a name="line.32"></a>
<span class="sourceLineNo">033</span> *<a name="line.33"></a>
<span class="sourceLineNo">034</span> * &lt;p&gt;<a name="line.34"></a>
<span class="sourceLineNo">035</span> * Multiple reference paths may be specified; if so, all of the specified paths are monitored together, and they all<a name="line.35"></a>
<span class="sourceLineNo">036</span> * must emit {@link org.jsimpledb.change.FieldChange}s compatible with the method's parameter type. Therefore, when<a name="line.36"></a>
<span class="sourceLineNo">037</span> * mutiple fields are monitored, the method's parameter type may need to be widened (either in raw type, generic type<a name="line.37"></a>
<span class="sourceLineNo">038</span> * parameters, or both).<a name="line.38"></a>
<span class="sourceLineNo">039</span> * &lt;/p&gt;<a name="line.39"></a>
<span class="sourceLineNo">040</span> *<a name="line.40"></a>
<span class="sourceLineNo">041</span> * &lt;p&gt;<a name="line.41"></a>
<span class="sourceLineNo">042</span> * As a special case, if zero fields are specified, then "wildcard" monitoring of every field in the local object occurs.<a name="line.42"></a>
<span class="sourceLineNo">043</span> * However in this case, only fields that emit changes compatible with the method's parameter type will be monitored.<a name="line.43"></a>
<span class="sourceLineNo">044</span> * So for example, a method taking a {@link org.jsimpledb.change.SetFieldChange} would receive notifications about<a name="line.44"></a>
<span class="sourceLineNo">045</span> * changes to all {@code Set} fields in the class, but not any other fields.<a name="line.45"></a>
<span class="sourceLineNo">046</span> * &lt;/p&gt;<a name="line.46"></a>
<span class="sourceLineNo">047</span> *<a name="line.47"></a>
<span class="sourceLineNo">048</span> * &lt;p&gt;&lt;b&gt;Instance vs. Static Methods&lt;/b&gt;&lt;/p&gt;<a name="line.48"></a>
<span class="sourceLineNo">049</span> *<a name="line.49"></a>
<span class="sourceLineNo">050</span> * &lt;p&gt;<a name="line.50"></a>
<span class="sourceLineNo">051</span> * If the method is an instance method, then {@link #startType} must be left unset; if the instance is a static<a name="line.51"></a>
<span class="sourceLineNo">052</span> * method, then {@link #startType} may be explicitly set, or if left unset it defaults to the class containing<a name="line.52"></a>
<span class="sourceLineNo">053</span> * the annotated method.<a name="line.53"></a>
<span class="sourceLineNo">054</span> * &lt;/p&gt;<a name="line.54"></a>
<span class="sourceLineNo">055</span> *<a name="line.55"></a>
<span class="sourceLineNo">056</span> * &lt;p&gt;<a name="line.56"></a>
<span class="sourceLineNo">057</span> * For an instance method, the method will be invoked on &lt;i&gt;each object&lt;/i&gt; for which the changed field is<a name="line.57"></a>
<span class="sourceLineNo">058</span> * found at the end of the specified reference path &lt;i&gt;starting from that object&lt;/i&gt;.<a name="line.58"></a>
<span class="sourceLineNo">059</span> * &lt;/p&gt;<a name="line.59"></a>
<span class="sourceLineNo">060</span> *<a name="line.60"></a>
<span class="sourceLineNo">061</span> * &lt;p&gt;<a name="line.61"></a>
<span class="sourceLineNo">062</span> * If the annotated method is a static method, the method is invoked &lt;i&gt;once&lt;/i&gt; if any instance exists for which the<a name="line.62"></a>
<span class="sourceLineNo">063</span> * changed field is found at the end of the specified reference path, no matter how many such instances there are.<a name="line.63"></a>
<span class="sourceLineNo">064</span> * Otherwise the behavior is the same.<a name="line.64"></a>
<span class="sourceLineNo">065</span> * &lt;/p&gt;<a name="line.65"></a>
<span class="sourceLineNo">066</span> *<a name="line.66"></a>
<span class="sourceLineNo">067</span> * &lt;p&gt;&lt;b&gt;Notification Delivery&lt;/b&gt;&lt;/p&gt;<a name="line.67"></a>
<span class="sourceLineNo">068</span> *<a name="line.68"></a>
<span class="sourceLineNo">069</span> * &lt;p&gt;<a name="line.69"></a>
<span class="sourceLineNo">070</span> * Notifications are delivered synchronously within the thread the made the change, after the change is made and just<a name="line.70"></a>
<span class="sourceLineNo">071</span> * prior to returning to the original caller.<a name="line.71"></a>
<span class="sourceLineNo">072</span> * Additional changes made within an {@link OnChange &amp;#64;OnChange} handler that themselves result in notifications<a name="line.72"></a>
<span class="sourceLineNo">073</span> * are also handled prior to returning to the original caller. Therefore, infinite loops are possible if an<a name="line.73"></a>
<span class="sourceLineNo">074</span> * {@link OnChange &amp;#64;OnChange} handler method modifies the field it's monitoring (directly, or indirectly via<a name="line.74"></a>
<span class="sourceLineNo">075</span> * other {@link OnChange &amp;#64;OnChange} handler methods).<a name="line.75"></a>
<span class="sourceLineNo">076</span> * &lt;/p&gt;<a name="line.76"></a>
<span class="sourceLineNo">077</span> *<a name="line.77"></a>
<span class="sourceLineNo">078</span> * &lt;p&gt;<a name="line.78"></a>
<span class="sourceLineNo">079</span> * {@link OnChange &amp;#64;OnChange} functions within a single transaction; it does not notify about changes that<a name="line.79"></a>
<span class="sourceLineNo">080</span> * may have occurred in a different transaction.<a name="line.80"></a>
<span class="sourceLineNo">081</span> * &lt;/p&gt;<a name="line.81"></a>
<span class="sourceLineNo">082</span> *<a name="line.82"></a>
<span class="sourceLineNo">083</span> * &lt;p&gt;&lt;b&gt;Other Notes&lt;/b&gt;&lt;/p&gt;<a name="line.83"></a>
<span class="sourceLineNo">084</span> *<a name="line.84"></a>
<span class="sourceLineNo">085</span> * &lt;p&gt;<a name="line.85"></a>
<span class="sourceLineNo">086</span> * No notifications are delivered for "changes" that do not actually change anything (e.g., setting a simple field to<a name="line.86"></a>
<span class="sourceLineNo">087</span> * the value already contained in that field, or adding an element to a set which is already contained in the set).<a name="line.87"></a>
<span class="sourceLineNo">088</span> * &lt;/p&gt;<a name="line.88"></a>
<span class="sourceLineNo">089</span> *<a name="line.89"></a>
<span class="sourceLineNo">090</span> * &lt;p&gt;<a name="line.90"></a>
<span class="sourceLineNo">091</span> * For any given field change and path, only one notification will be delivered per recipient object, even if the changed field<a name="line.91"></a>
<span class="sourceLineNo">092</span> * is seen through the path in multiple ways (e.g., via reference path {@code "mylist.element.myfield"} where the changed object<a name="line.92"></a>
<span class="sourceLineNo">093</span> * containing {@code myfield} appears multiple times in {@code mylist}).<a name="line.93"></a>
<span class="sourceLineNo">094</span> * &lt;/p&gt;<a name="line.94"></a>
<span class="sourceLineNo">095</span> *<a name="line.95"></a>
<span class="sourceLineNo">096</span> * &lt;p&gt;<a name="line.96"></a>
<span class="sourceLineNo">097</span> * See {@link org.jsimpledb.core.Transaction#addSimpleFieldChangeListener Transaction.addSimpleFieldChangeListener()}<a name="line.97"></a>
<span class="sourceLineNo">098</span> * for further information on other special corner cases.<a name="line.98"></a>
<span class="sourceLineNo">099</span> * &lt;/p&gt;<a name="line.99"></a>
<span class="sourceLineNo">100</span> *<a name="line.100"></a>
<span class="sourceLineNo">101</span> * @see org.jsimpledb.ReferencePath<a name="line.101"></a>
<span class="sourceLineNo">102</span> * @see org.jsimpledb.change<a name="line.102"></a>
<span class="sourceLineNo">103</span> */<a name="line.103"></a>
<span class="sourceLineNo">104</span>@Retention(RetentionPolicy.RUNTIME)<a name="line.104"></a>
<span class="sourceLineNo">105</span>@Target(ElementType.METHOD)<a name="line.105"></a>
<span class="sourceLineNo">106</span>@Documented<a name="line.106"></a>
<span class="sourceLineNo">107</span>public @interface OnChange {<a name="line.107"></a>
<span class="sourceLineNo">108</span><a name="line.108"></a>
<span class="sourceLineNo">109</span>    /**<a name="line.109"></a>
<span class="sourceLineNo">110</span>     * Specifies the path to the target field to watch for changes.<a name="line.110"></a>
<span class="sourceLineNo">111</span>     * See {@link org.jsimpledb.ReferencePath} for information on the proper syntax.<a name="line.111"></a>
<span class="sourceLineNo">112</span>     *<a name="line.112"></a>
<span class="sourceLineNo">113</span>     * &lt;p&gt;<a name="line.113"></a>
<span class="sourceLineNo">114</span>     * Multiple paths may be specified; if so, each path is handled as a separate independent listener registration,<a name="line.114"></a>
<span class="sourceLineNo">115</span>     * and the method's parameter type must be compatible with at least one of the {@link org.jsimpledb.change.FieldChange}<a name="line.115"></a>
<span class="sourceLineNo">116</span>     * sub-types emitted by each field. If zero paths are specified, every field in the class (including superclasses)<a name="line.116"></a>
<span class="sourceLineNo">117</span>     * that emits {@link org.jsimpledb.change.FieldChange}s compatible with the method parameter will be monitored for changes.<a name="line.117"></a>
<span class="sourceLineNo">118</span>     * &lt;/p&gt;<a name="line.118"></a>
<span class="sourceLineNo">119</span>     *<a name="line.119"></a>
<span class="sourceLineNo">120</span>     * @return reference path leading to the changed field<a name="line.120"></a>
<span class="sourceLineNo">121</span>     * @see org.jsimpledb.ReferencePath<a name="line.121"></a>
<span class="sourceLineNo">122</span>     */<a name="line.122"></a>
<span class="sourceLineNo">123</span>    String[] value() default { };<a name="line.123"></a>
<span class="sourceLineNo">124</span><a name="line.124"></a>
<span class="sourceLineNo">125</span>    /**<a name="line.125"></a>
<span class="sourceLineNo">126</span>     * Specifies the starting type for the {@link org.jsimpledb.ReferencePath} specified by {@link #value}.<a name="line.126"></a>
<span class="sourceLineNo">127</span>     *<a name="line.127"></a>
<span class="sourceLineNo">128</span>     * &lt;p&gt;<a name="line.128"></a>
<span class="sourceLineNo">129</span>     * This property must be left unset for instance methods. For static methods, if this property is left unset,<a name="line.129"></a>
<span class="sourceLineNo">130</span>     * then then class containing the annotated method is assumed.<a name="line.130"></a>
<span class="sourceLineNo">131</span>     * &lt;/p&gt;<a name="line.131"></a>
<span class="sourceLineNo">132</span>     *<a name="line.132"></a>
<span class="sourceLineNo">133</span>     * @return Java type at which the reference path starts<a name="line.133"></a>
<span class="sourceLineNo">134</span>     * @see org.jsimpledb.ReferencePath<a name="line.134"></a>
<span class="sourceLineNo">135</span>     */<a name="line.135"></a>
<span class="sourceLineNo">136</span>    Class&lt;?&gt; startType() default void.class;<a name="line.136"></a>
<span class="sourceLineNo">137</span><a name="line.137"></a>
<span class="sourceLineNo">138</span>    /**<a name="line.138"></a>
<span class="sourceLineNo">139</span>     * Determines whether this annotation should also be enabled for<a name="line.139"></a>
<span class="sourceLineNo">140</span>     * {@linkplain org.jsimpledb.SnapshotJTransaction snapshot transaction} objects.<a name="line.140"></a>
<span class="sourceLineNo">141</span>     * If unset, notifications will only be delivered to non-snapshot (i.e., normal) database instances.<a name="line.141"></a>
<span class="sourceLineNo">142</span>     *<a name="line.142"></a>
<span class="sourceLineNo">143</span>     * @return whether enabled for snapshot transactions<a name="line.143"></a>
<span class="sourceLineNo">144</span>     * @see org.jsimpledb.SnapshotJTransaction<a name="line.144"></a>
<span class="sourceLineNo">145</span>     */<a name="line.145"></a>
<span class="sourceLineNo">146</span>    boolean snapshotTransactions() default false;<a name="line.146"></a>
<span class="sourceLineNo">147</span>}<a name="line.147"></a>
<span class="sourceLineNo">148</span><a name="line.148"></a>




























































</pre>
</div>
</body>
</html>
